package com.starview.star.data.indextree;

import java.util.Map.Entry;

import com.starview.star.compiler.util.PrettyPrintable;

/**
 * Interface for applicative (aka persistent) maps.
 * 
 * It is not permitted for a value to be null.
 * 
 * @author fgm
 * 
 * @param <K>
 *          the type of the key
 * @param <V>
 *          the type of the value
 */
public interface Mapping<K, V> extends PrettyPrintable, Iterable<Entry<K, V>>
{
  /**
   * Is the map empty?
   * 
   * @return
   */
  boolean isEmpty();

  /**
   * How many elements in the map?
   * 
   * @return the number of kay/value pairs represented
   */
  public int size();

  /**
   * Find the value associated with a key.
   * 
   * @param key
   * @return the value, or null if the key is not present.
   */
  V find(K key);

  /**
   * test to see if there is a value associated with the key
   * 
   * @param key
   * @return true if there is
   */
  boolean contains(K key);

  /**
   * Create a new Mapping that results from adding the key/value pair to the map.
   * 
   * @param key
   * @param value
   * @return a new mapping. It is required that this operation does NOT affect the original mapping.
   */
  Mapping<K, V> insrt(K key, V value);

  /**
   * create a new mapping that results from deleting any mapping associated with the key. It is not
   * required that there previously existed an entry for the key.
   * 
   * @param key
   * @return a new mapping with no entry in it for the key. It is required that this operation does
   *         not affect the original mapping.
   */
  Mapping<K, V> delete(K key);
}
